home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / misc / WreadFiles47.lha / Wread.doc < prev    next >
Encoding:
Text File  |  1994-11-25  |  35.5 KB  |  800 lines

  1.  
  2.   * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  3.   *                                                                       *
  4.   *                      WreadFiles Program Documentation                 *
  5.   *                                                                       *
  6.   *  Version 4.7                              M.L. Barlow  November 1994  *
  7.   * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  8.  
  9.   INTRODUCTION. 
  10.  
  11.   What it Does:
  12.  
  13.     WreadFiles is a vocal text file reader program for use on the Commodore
  14.   Amiga.  The text is both printed to the screen and spoken.  The basic
  15.   features are summarized as follows:
  16.  
  17.   o    Text is read in sentences rather than lines. 
  18.  
  19.   o    Dynamic Speech Correction on over 4000 word or word fragments. 
  20.  
  21.   o    4.2 Reading Rate: 850 bytes/minute (A1000, CPU 68000). 
  22.  
  23.   o    4.2 Reading Rate: 1190 bytes/minute (A3000, CPU 68030). 
  24.   
  25.   o    Corrected Pronunciation of many place and personal names. 
  26.  
  27.   o    Corrected Pronunciation of some foreign names and expressions. 
  28.  
  29.   o    Corrected Pronunciation of many abbreviations containing vowels. 
  30.  
  31.   o    Expansion of many capitalized abbreviations. 
  32.  
  33.   o    Standard pronunciation of many multi-digit numbers. 
  34.  
  35.   o    ANSI color codes stripped from text displayed or spoken. 
  36.  
  37.   o    Ignores repeated characters. 
  38.  
  39.   o    Different voices for user interface and reading. 
  40.  
  41.   <    Alternate voice for text delineated by brackets. 
  42.   ->   These brackets are often used to identify quoted text.        <-
  43.   <<   Three basic types are supported.  Single or double brackets   >>
  44.   >    may be forward or reverse, left side only or left and right.  <
  45.  
  46.   o    Single file or indexed multi-file read modes. 
  47.  
  48.   o    Run from Workbench or CLI. 
  49.  
  50.   o    Used with A1000 (OS 1.3) and A3000 (OS 2.04-2.1)
  51.  
  52.                 --- New With Version 4.7 --
  53.  
  54.   o    4.7 Reading Rate: 920 bytes/minute (A1000, CPU 68000). 
  55.  
  56.   o    4.7 Reading Rate: 1290 bytes/minute (A4000, CPU 68040). 
  57.  
  58.   o    ASL file requester for input file selection for OS 2.04+.
  59.  
  60.   o    Alternate high-contrast color setup: white text on black background
  61.        in addition to the normal black text on lavender green.
  62.  
  63.   o    Program icon tooltypes now enable user pre-selection of reading
  64.        rate, color and full screen ASL file requester.
  65.  
  66.   o    Used with A4000 (OS 3.0)
  67.  
  68.   ----------------------------------------------------------------------
  69.  
  70.   COPYRIGHT
  71.  
  72.     The Author RESERVES the option to copyright this program.  By the
  73.   provisions of the Hague Copyright Convention, to which the U.S. has
  74.   recently become a signatory, I am reserving the option to copyright this
  75.   program.  Any reproduction of WreadFiles, in whole or in part, without my
  76.   permission is a potential copyright violation. 
  77.  
  78.     Permission is granted for telecommunication services to distribute this
  79.   program if distributed unmodified and intact with this documentation and if
  80.   no special charges beyond the normal service rates are made.  This program
  81.   may also be included on public domain software disks if distributed on a
  82.   non-profit basis under the same conditions as above. 
  83.  
  84.     I am not requesting payment from any person receiving this program under
  85.   the conditions above.  If you were charged for any version of this
  86.   program from 4.2 through 4.7 beyond the limits set forth above then you
  87.   may have been defrauded.
  88.  
  89.     Anyone distributing modified or incomplete versions of this program or
  90.   documentation may be fully liable for any consequence of such action. 
  91.  
  92.     I have not yet formally copyrighted WreadFiles as it is my judgement
  93.   that this program is not of "commercial" quality in its current state and
  94.   that there is not a commercially viable market for a program of this type. 
  95.  
  96.   ----------------------------------------------------------------------
  97.  
  98.   PREREQUISITES
  99.  
  100.      WreadFiles uses the USA versions of Amiga translator.library and
  101.   narrator.device provided with Commodore Amiga operating systems 2.04 and
  102.   earlier to generate speech.  It has been reported that Commodore did not
  103.   include these files with the newer operating systems due to a dispute
  104.   with the developer.  I do not know if there is a legal method of obtaining
  105.   these files if you have not purchased OS 2.04 or earlier.  WreadFiles will
  106.   not run if you have a later version of the operating system lacking these
  107.   files or if you have removed the translator.library or the narrator.device
  108.   from your Workbench disk. 
  109.  
  110.     Fonts: WreadFiles will attempt to load either the clean 8 font, the
  111.   pearl 8 font, or the topaz 8 font in that order.  If the first font found
  112.   is one you have replaced with a larger or smaller font, then WreadFiles
  113.   may not function properly.  Versions of the clean.font or pearl.font
  114.   which have the control characters defined are recommended (in the event
  115.   the file you try to read has control characters in it). 
  116.  
  117.   ----------------------------------------------------------------------
  118.  
  119.     INSTALLATION
  120.  
  121.      There are no extra configuration or setup files required for this
  122.   program.  All user configurable options are implemented as tooltypes of the
  123.   WreadFiles.info icon. It may be installed on a floppy or hard disk.  For
  124.   the OS 1.3 or earlier operating systems, I find it most convenient to
  125.   install WreadFiles on the root directory of the hard disk so that its icon
  126.   is directly available.  With OS 2.0x the "leave out" option in the
  127.   Workbench Icons menu will accomplish the same function if the program and
  128.   its icon are in a subdirectory.  There should be no reason to change your
  129.   Startup-Sequence for this program.  You may wish to add a shorthand alias,
  130.   for CLI use, to your Shell-Startup such as:
  131.  
  132. alias Wread run >NIL: sys:system/WreadFiles []
  133.  
  134.   if Wreadfiles were in your sys:system directory.  This is not required
  135.   and I do not recommend that you do this if you have any doubts about this
  136.   process. 
  137.  
  138.     You may rename your copy of the program if you wish. 
  139.  
  140. ----------------------------------------------------------------------
  141.  
  142.   OPERATING MODES
  143.  
  144.     WreadFiles has two basic operating modes: single file mode and index file
  145.   mode.  In single file mode WreadFiles is given the name of a single file to
  146.   read.  This is the default mode of the program and no special action is
  147.   required to invoke it.
  148.  
  149.     In index file mode WreadFiles is given the name of a text file which
  150.   contains a list of files to read.  The index may contain as many as 300
  151.   files which will be read automatically in the sequence listed.  You invoke
  152.   the index file mode by typing an @ character before entering the file
  153.   name in the program's requester or on the CLI line.  If a file name starts
  154.   with an @ character, place a single quote (') ahead of the name to enable
  155.   reading it as a single file.
  156.  
  157.    Index file ICONS are identified by a MODE=filelist tool type entry. 
  158.  
  159.   ----------------------------------------------------------------------
  160.  
  161.   RUNNING THE PROGRAM
  162.  
  163.     There are four basic methods of starting WreadFiles.  Mode 2 below is
  164.   the best method for general use with Workbench, especially with OS 2.0x. 
  165.  
  166.     In each case WreadFiles will start using the command color palette and
  167.   using the control voice (Andy).  As soon as the file to read is loaded,
  168.   the screen will switch to the text color palette and the voice will
  169.   switch to the reading voice (Tex).  There may be a slight cough or pop
  170.   at the very beginning as WreadFiles clears its throat (initializes the
  171.   narrator). 
  172.  
  173.   A. Method 1: Directly From its Workbench Icon. 
  174.  
  175.     Running WreadFiles from its Workbench icon is the most direct way to  
  176.   start WreadFiles.  For versions 4.2 and below, you must know the full CLI
  177.   name of the file you wish to read as there is no internal file selector. 
  178.   The program will say "hello there" and ask for a file name.
  179.  
  180.     A standard ASL file requester will appear if you are using OS 2.04 or
  181.   greater.  That requester will provide a filtered list of the files
  182.   available (#?.info, #?.o, #?.lzh and #?.lha files are not listed) This will
  183.   allow you to search for the file you wish to hear.
  184.  
  185.     Enter the file name in the text gadget presented.  If the file is an
  186.   index file (you must know this) then place an @ character ahead of the file
  187.   name.  If the program cannot access the file name entered then the program
  188.   will apologize and exit with a red screen abort.  Also, if you push enter
  189.   without entering or selecting a filename, WreadFiles will assume that you
  190.   wish to abort(quit).  This is also what happens if you select the "Abort"
  191.   gadget on the ASL requester.
  192.  
  193.   The following are sample non-ASL entries:
  194.  
  195.     |-----------------------|
  196.     | ram:wread.doc         |      single file name: ram:wread.doc
  197.     |=======================|
  198.     | @ram:File_list        |      index file name:  ram:File_list
  199.     |=======================|
  200.     | '@oddname             |      single file name: @oddname
  201.     |=======================|
  202.     | @@oddlist             |      index file name:  @oddlist
  203.     |-----------------------|
  204.  
  205.   To select an index file with the ASL requester, you must insert an '@'
  206.   symbol ahead of the selected file name in the bottom text box.
  207.  
  208.   B. Method 2: Using Extended (shift) Icon Select
  209.  
  210.     Extended Select is the easiest method of selecting the file to be read
  211.   from Workbench.  For best operation, the WreadFiles icon and the icon for
  212.   the target file to be read should both be visible.  The icon for the target
  213.   file may be an OS 2.x pseudo-icon displayed with the "view all files"
  214.   window option set.  The procedure is as follows:
  215.  
  216.   First: Single click on the WreadFiles icon.  A face should appear on the
  217.          icon. 
  218.  
  219.   Second: Push and hold either shift key down and then: double click on the
  220.           icon for the target file to be read. 
  221.  
  222.   The program will say "hello there" and acknowledge the selection of the
  223.   file before reading it. 
  224.  
  225.     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  226.     *                                                                     *
  227.     *  NOTE:  This file, Wread.doc, has been created with a standard      *
  228.     *  sys:utilities/more project icon.  You may use the method above to  *
  229.     *  have WreadFiles read this file for you.  Read the Caveats and      *
  230.     *  Warnings first!                                                    *
  231.     *                                                                     *
  232.     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  233.  
  234.   C. Method 3: WreadFiles Project Icon Select. 
  235.  
  236.     If the file has a true WreadFiles Project icon, then it is only necessary
  237.   to double click that icon to start WreadFiles.  This method requires that
  238.   WreadFiles be located on a fixed directory path in your system so that the
  239.   default tool entry is always valid.  The following is an example of such
  240.   an entry:
  241.                   ========================
  242.    Default Tool:  |sys:system/WreadFiles |
  243.                   ========================
  244.  
  245.    D. Method 4: From the CLI. 
  246.  
  247.      Finally, you may start WreadFiles from the CLI just like any other CLI
  248.   function.  If you just type:
  249.  
  250. 1> directory_name/WreadFiles
  251.  
  252.   then WreadFiles will start up the same as in method (1) above.  You may
  253.   also provide the name of the target file to be read on the CLI command line
  254.   in lieu of entering it in the program.  An example of this might be the
  255.   line:
  256.  
  257. 1> ram:WreadFiles ram:Wread.doc
  258.  
  259.   An example of calling an index file, df0:Wread.list, is:
  260.  
  261. 1> dh0:WreadFiles @df0:Wread.list
  262.  
  263.     WreadFiles can be used by a CLI batch file with commands like
  264.   those above. 
  265.  
  266.   ----------------------------------------------------------------------
  267.  
  268.   USING THE PROGRAM: MENU OPTIONS
  269.  
  270.     When a menu option is selected, the screen will change to command
  271.   colors and the control voice will announce the selection. 
  272.  
  273.     WreadFiles cannot respond to commands while it is reading a sentence. 
  274.   Thus the program's response to a menu selection will be delayed until
  275.   after it has finished reading the current sentence.  WreadFiles does
  276.   limit the length of any sentence to one screen of text to prevent
  277.   intolerable delays.  Command delay is not a problem with normal text. 
  278.  
  279.   A. Project Menu
  280.  
  281.      1. Start Over [Pick File]: Right-Amiga P
  282.  
  283.         Selecting this option in single file mode will restart reading from
  284.      the beginning.  In index file mode this is the Pick File option. 
  285.      Pick File presents a menu of the files on the index for selecting the
  286.      next file to read. 
  287.  
  288.      2. Skip this File: Right-Amiga S
  289.  
  290.         Selecting this option in single file mode is the same as selecting
  291.      Exit/Quit.  In index file mode this option aborts reading the
  292.      current file and goes on to the next file or exits the program if the
  293.      last file was being read. 
  294.  
  295.      3. Exit/Quit: Right-Amiga Q
  296.  
  297.         Ends the program.  The program will acknowledge that you have opted
  298.       to exit and say good-bye. 
  299.  
  300.   B. Options Menu
  301.  
  302.      1. Speech Correction:  Right-Amiga C
  303.  
  304.         Toggles Correction on and off.  When speech correction is off, the
  305.      default translator is restored.  Only sentence processing is done by
  306.      the program when speech correction is off.  The control voice will
  307.      announce whether speech correction is being enabled or disabled. 
  308.  
  309.      2. Pick Reading Rate: Right-Amiga R
  310.  
  311.         Allows you to pick the reading rate.  For fast processors the
  312.      default reading rate is 210 words per minute.  For slower Amigas, such
  313.      as the A1000, the default rate is set at 250 words per minute to
  314.      compensate for the longer processing time required. 
  315.  
  316.      3. Next Display Palette: Right-Amiga D
  317.  
  318.         Switch from normal palette (black text on lavender background) to
  319.      the high contrast palette (white text on black) or vice versa.  The
  320.      high contrast palette has been added at the request of a user for
  321.      better visibility. 
  322.  
  323.  
  324.   C. Icon Menu
  325.  
  326.        The Icon Menu is only available if the target file to be read has been
  327.      selected by name (start-up methods 1 or 4 above). 
  328.  
  329.      Notes:
  330.  
  331.      1.  Do not have two disks with the SAME volume name in your system
  332.      when you use these options. 
  333.  
  334.      2. These icon create/modify options are the only functions of this
  335.      program which will write to your disk.  If you have any concern about
  336.      the compatibility of WreadFiles with your system, I recommend that you
  337.      avoid creating or modifying icons while multitasking or using disks
  338.      containing valuable non-replaceable data.  The only problem I have had
  339.      with the current versions of these functions has been icons ending up
  340.      on the wrong disk when disks with duplicate volume names were in the
  341.      system. 
  342.  
  343.      1. Make New Icon
  344.  
  345.         Creates a new project icon with WreadFiles as the default tool.  If
  346.      the file is an index file then the MODE=filelist tool type will be
  347.      added.  Otherwise a default MODE=singlefile tool type will be used. 
  348.  
  349.      2. Modify Old Icon
  350.  
  351.         Attempts to modify the default tool and tool types entry of the
  352.      existing icon of the file or index file selected at start-up without
  353.      changing its image.  If no existing icon is found for that file, then a
  354.      new icon will be made. 
  355.  
  356.   D. [Copyright]  "Menu"
  357.  
  358.        This is not a menu but a notice:
  359.  
  360.                        |===========================|
  361.                        |  The Author RESERVES the  |
  362.                        |  option to copyright      |
  363.                        |  this program.            |
  364.                        |                           |
  365.                        |       M.L. Barlow         |
  366.                        |    Silverdale, WA, USA    |
  367.                        |===========================|
  368.  
  369.   ----------------------------------------------------------------------
  370.  
  371.   USING THE PROGRAM: KEYBOARD OPTIONS
  372.  
  373.   A. Menu Hot Keys. 
  374.  
  375.     The following are menu hot keys; see above for a description of the
  376.   menu functions. 
  377.  
  378.      1. Right-Amiga P ... Start Over [Pick File from index]
  379.  
  380.      2. Right-Amiga S ... Skip this File
  381.  
  382.      3. Right-Amiga Q ... Exit/Quit
  383.  
  384.      4. Right-Amiga C ... Speech Correction(on/off)
  385.  
  386.      5. Right-Amiga R ... Pick Reading Rate
  387.  
  388.      6. Right-Amiga D ... Next Display Palette (toggle)
  389.  
  390.   B. Keyboard Pause
  391.  
  392.      Striking any active key, other than those specified above, will pause
  393.   the program.  The screen color will change to command colors and the
  394.   control voice will announce that the program is paused.  WreadFiles will
  395.   remain paused until another key is struck.  The normal menu is removed
  396.   while the program is paused. 
  397.  
  398.   ----------------------------------------------------------------------
  399.  
  400.   USING THE PROGRAM: TOOL TYPE OPTIONS
  401.  
  402.     You may customize some features of this program by manually adding or
  403.   changing the tooltypes entries of the WreadFiles program icon.  This is
  404.   accomplished by selecting the icon (single click) and using the Workbench
  405.   [Project] Info menu item on OS 1.3 or the [Icons] information menu item on
  406.   OS 2.x/3.x.  There are three user selectable parameters available.  If the
  407.   program is started from the CLI, it will also search for its icon (eg.
  408.   WreadFiles.info) file and use the options found.
  409.  
  410.   A.  Reading Rate
  411.  
  412.    The reading rate may be set from 100 to 300 with an entry of the form: 
  413.  
  414.                              SPEAK_RATE=nnn 
  415.  
  416.   Where nnn is a three digit number from 100 to 300.  Invalid entries will be
  417.   ignored.  The rate you enter will override the normal preselected rate.
  418.  
  419.   B.  High Contrast Color Palette
  420.  
  421.   The high contrast color palette may be selected by an entry:
  422.  
  423.                             PRESET=hcontrast
  424.  
  425.   PRESET=normal is the default and does not have to be specified.  This
  426.   has been added only to provide a place for the active option.
  427.  
  428.   C.  Full Screen ASL Requester.
  429.  
  430.   A full screen width ASL requester may be specified by the entry:
  431.  
  432.                              ASL_SIZE=full
  433.  
  434.      When this option is selected, a special 320x200 low resolution screen
  435.   is created for the ASL requester to provide maximum readability.  The text
  436.   on this screen is twice as large as normal text.  ASL_SIZE=normal is the
  437.   default and does not have to be specified.  This text has been added only
  438.   to provide a place for the active option.  The normal ASL requester for
  439.   this program is full screen height and one third screen width.
  440.  
  441.     A sample Icon, WreadFiles.hc.info, is provided with some if these
  442.   options set.  If you use the CLI or a directory utility to rename
  443.   WreadFiles.info to WreadFiles.normal.info and then rename
  444.   WreadFiles.hc.info to WreadFiles.info then WreadFiles will come up in
  445.   hi-contrast mode with a speak rate of 180 and full screen ASL requester.
  446.  
  447.   ----------------------------------------------------------------------
  448.  
  449.   PROGRAM NOTES: MULTITASKING
  450.  
  451.     WreadFiles does multitask, even with itself.  I have run as many as 19
  452.   copies of the program simultaneously loaded on my A3000 with 10 megabytes
  453.   of memory.  A jumble of spoken text was produced as each copy took its turn
  454.   speaking a sentence.  This was done to test the stability of the program. 
  455.   Since the speech correction routine is continuously allocating and
  456.   de-allocating small chunks of memory, any problem with this routine could
  457.   result in these programs stepping on each other.  While the program passed
  458.   that test, it was not exhaustive.  The user is cautioned that no matter how
  459.   much testing I do, there is no guarantee that multitasking WreadFiles will
  460.   be safe on his or her system.  The program has also been tested with
  461.   mungwall and enforcer.  I did discover and fix an obscure problem in the
  462.   numeric handler which could cause a Guru.
  463.  
  464.     The CPU is under intensive use while this program is talking. This is a
  465.   serious limitation to effectively multitasking this program on 68000 based
  466.   systems.
  467.  
  468.   GENERAL WARNING
  469.  
  470.     I have noticed that some programs, such as AmigaBasic, may fail [GURU] if
  471.   they start using the audio hardware while another program is using the
  472.   narrator or audio system.  In each case where I have observed this with
  473.   WreadFiles running, the program in question will also fail if multitasked
  474.   with the Commodore Speak: device. I suspect these programs may not be
  475.   checking to see if their audio channels have not been reallocated to a
  476.   higher priority process before attempting to use them.
  477.  
  478.   ----------------------------------------------------------------------
  479.  
  480.   PROGRAM NOTES: FILE COMPATIBILITY
  481.  
  482.     WreadFiles works best with single column ASCII text files having a
  483.   maximum length of 80 characters.  These files are printed to the screen in
  484.   their original format.  The program recognizes ^J (CONTROL J which is ASCII
  485.   code 10), ^M, or sequential ^M^J or ^J^M as end of line (EOL)indicators. 
  486.   WreadFiles will strip out many standard ANSI escape sequences, such as
  487.   those used for color formatting (^[[33;41m).  The program ignores these
  488.   codes, since color is used by the program to show where active reading is
  489.   taking place. (Lines containing sentences which have been read are black
  490.   and the unread lines are blue.)
  491.  
  492.     If the text lines in the file are longer than 80 characters then the
  493.   program will reformat the lines to fit on the screen.  This also applies
  494.   to files which only have end of line indicators at the ends of paragraphs. 
  495.  
  496.     Files containing tables of numbers or mathematical formulas are not
  497.   recommended for use with WreadFiles.  The program works best with
  498.   narrative text. 
  499.  
  500.     If you attempt to read a specially formatted, word processor file
  501.   (or any binary file) the result will usually be gibberish.  Some word
  502.   processors which use near ASCII format (Scribble!) may be partially
  503.   readable. 
  504.  
  505.   ----------------------------------------------------------------------
  506.  
  507.   SHORT TEXT LINE FILES
  508.  
  509.     Since unusually short text lines (like the line above) are one of the
  510.   criteria that WreadFiles uses to identify sentence ends, files with narrow
  511.   text will not be properly processed.  The reading of files known to
  512.   be 60 or 40 characters wide, maximum, can be improved by adding one of the
  513.   two standard text width identifiers, {60} or {40} respectively, after the
  514.   file name.  The curly brackets are required.  At least one space must
  515.   precede the first bracket.  See the section on index files for an example. 
  516.  
  517.       WreadFiles project icons may also contain a text width code with a tool
  518.  type of the form:
  519.  
  520. MODE=singlefile,40
  521.  
  522.     This type of entry is not relevant for index file icons because that
  523.   information is contained in the file. 
  524.  
  525.   ----------------------------------------------------------------------
  526.  
  527.   INDEX FILES
  528.  
  529.     Index files are ASCII text files where each line contains a file
  530.   description in the first 41 characters of the line and a file name which
  531.   begins at the 42nd character.  The file description is what the user will
  532.   see if he uses the Pick File option.  The file name is what WreadFiles uses
  533.   to access the file.  If any file cannot be accessed by the name provided
  534.   then the program will "good-bye" with a red screen abort.  For best
  535.   results, use the volume name rather than device name to identify the root
  536.   directory of each file.  The entry can also contain the narrow text width
  537.   indicators.  An example of a typical entry line is as follows:
  538.  
  539. File description               File name at column 42       Text width code
  540. |                                        |                         |
  541. SuperWord from GnSoft by Ron Jennings    UG_Disk:Reviews/SuperWord {60}
  542.  
  543.     In this example, the file name is followed by an optional text width
  544.   code.  The entries should be sequential with no blank lines.  The last text
  545.   line should end with a carriage return.  Lines will be ignored which
  546.   reference the same file name as that of the preceding line. 
  547.  
  548.   ----------------------------------------------------------------------
  549.  
  550.   PROGRAM NOTES: HOW IT WORKS:
  551.  
  552.      The text is spoken one sentence at a time to achieve a natural speech
  553.   rhythm.  WreadFiles uses standard punctuation marks and other criteria to
  554.   determine where the sentence breaks are. 
  555.  
  556.     Each sentence is scanned for over 4000 word or word fragments which are
  557.   mispronounced by the Amiga translator or are associated with mispronounced
  558.   words.  These words (or word fragments) are replaced dynamically on the fly
  559.   with text which will be more correctly pronounced.  The target text may be
  560.   replaced unconditionally whenever found, or only if qualified by the
  561.   adjacent text. 
  562.  
  563.     There are cases where two common words are spelled the same, (homographs)
  564.   but pronounced differently.  WreadFiles may attempt to determine the right
  565.   pronunciation by examining the adjacent words. 
  566.  
  567.     Most of the text replacements are not case sensitive.  Case sensitive
  568.   changes are primarily for standard capitalized abbreviations and acronyms.
  569.   These may be rendered as letters (AFL => ay.f.l) or expanded to their
  570.   original form (BTW => buy the way,).  The program processes many standard
  571.   abbreviations and BBS abbreviations.  This reduces the number of cases
  572.   where it is necessary to look at the screen to see what was said.  Common
  573.   state two letter designations (WA) are expanded unless they are easily
  574.   confused with  common words (HI).  Many common abbreviations such as those
  575.   for months of the year and days of the week are also expanded on a non case
  576.   sensitive basis. 
  577.  
  578.     Occasionally these expansions are inappropriate; such as when the AZ text
  579.   editor is rendered as the "Arizona" text editor. 
  580.  
  581.      Standard multi-digit numbers are also replaced by text to sound more
  582.   natural. No expansion occurs for numbers of longer than 15 digits or if there
  583.   are 15 more digits than text characters in a sentence.  WreadFiles is
  584.   usually able to convert The dollar sign preceding a number to the
  585.   appropriate text following the number. A limited attempt is made to
  586.   determine if the dollar sign is a hexadecimal number indicator and if the
  587.   number is part of a hexadecmal string.
  588.  
  589.      WreadFiles attempts to identify and remove cosmetic text patterns from
  590.   what is spoken so that the listener does not have to hear such things as
  591.   the word "asterisk" repeated 76 times.  The program cannot protect the
  592.   listener from general ASCII art, but it will remove some combinations
  593.   of slashes, spaces and backslashes which are abnormal for spoken text. 
  594.  
  595.      Most speech correction changes are made by modifying the text given to
  596.   the translator.  There are also changes made to the translator output.  For
  597.   some words there was no way to force the translator to produce the correct
  598.   phonetic translation.  For these cases, the abnormal consonant cluster zv
  599.   was selected to serve as a marker for changes to be made to the translator
  600.   output (e.g. breezvth, ayzvsheya, pzvissihfihk, etc.)  Some translator
  601.   output vowel codes are also changed in cases where they did not sound right
  602.   when combined with specific consonants. 
  603.  
  604.   ----------------------------------------------------------------------
  605.  
  606.   PROGRAM NOTES: POTENTIAL APPLICATIONS
  607.  
  608.   The following are potential applications of this program:
  609.  
  610.   A. Reading ASCII Text Files. 
  611.  
  612.      WreadFiles may be used to read standard ASCII text files.  In this
  613.   application using WreadFiles is similar to typing a file to SPEAK: except
  614.   that WreadFiles also displays the text being read and  provides extensive
  615.   preprocessing of the text to remove most of the words mispronounced by the
  616.   translator.library (on a frequency of use basis). 
  617.  
  618.   B. Talking Story Disk
  619.  
  620.      WreadFiles could be used for a non-commercial talking story disk.  The
  621.   index file mode would be best for that type of application.  The 244 kbyte
  622.   size of this file, mostly due to the embedded speech correction data, will
  623.   limit the text on a nominal 880 kbyte disk to about 528 kbytes.  This amount
  624.   of material would take about 9 hours and 20 minutes to read on an A3000 (or
  625.   other 68030 based Amiga) or a little over 13 hours on a non-accelerated
  626.   A1000,  A500, or A2000. 
  627.  
  628.   C. Aid For Visually Impaired
  629.  
  630.     While WreadFiles has not been specifically written for this application,
  631.   I have made the menu selection boxes large so that someone with minor
  632.   visual impairment might make them out.  Perhaps WreadFiles combined with
  633.   another utility would be beneficial for people with more severe visual
  634.   impediments.  WreadFiles does allow other programs to obtain access to the
  635.   translator, narrator, and audio.device between each sentence break. 
  636.  
  637.  
  638.   ----------------------------------------------------------------------
  639.  
  640.   PROGRAM NOTES: DEFICIENCIES
  641.  
  642.     My primary emphasis on WreadFiles has been the speech correction. 
  643.   There remain several areas where this program should be improved. 
  644.   Correcting all these deficiencies could cause the code size to grow
  645.   another 50 - 100 kbytes. 
  646.  
  647.   A. No User Scrolling. 
  648.  
  649.     No user scrolling capability is provided.  Adding this feature would not
  650.   be simple because the input text buffer is modified as it is read.  This
  651.   minimizes buffer preprocessing delays. 
  652.  
  653.     It is possible to scroll through the list of the files to be read in
  654.   index mode, however this is not a substitute for being able to quickly
  655.   scroll forward and backward through the file being read. 
  656.  
  657.   B. No File Selector, version 4.2 and earlier. 
  658.  
  659.     There is no program file selector on versions 4.2 and earlier.  Such
  660.   selectors are standard on most Amiga programs.  The standard ASL file
  661.   requester has been added for versions 4.3 and greater. OS 2.04 or greater
  662.   is required for this feature.
  663.  
  664.   C. Sentence Speaking Cannot Be Interrupted. 
  665.  
  666.     This is normally not a problem.  However, if you load a file which
  667.   contains a long segment of text lacking the criteria which identify
  668.   sentence breaks, then the program may not respond to your commands or
  669.   attempts to stop the program for several minutes. 
  670.  
  671.   D. No ARexx Port
  672.  
  673.     It is conceivable that an ARexx port could be useful for interactive
  674.   multitasking.  I have not yet considered what should be done in this
  675.   regard. 
  676.  
  677.   ----------------------------------------------------------------------
  678.  
  679.   CAVEATS AND WARNINGS
  680.  
  681.     This is a program I wrote initially for my own use.  No warranty is made
  682.   on the accuracy of this documentation or the fitness of this software for
  683.   any purpose.  The speech correction routines in WreadFiles are tightly
  684.   "tuned" to the existing USA, OS 1.3 and 2.04 versions of the
  685.   translator.library and narrator.device.  There is no guarantee that future
  686.   improvements in the operating system software will not degrade or disrupt
  687.   the operation of this program.  Also, since Commodore did not renew its
  688.   license to sell these products, it is quite likely that any replacement
  689.   system would be incompatible with this program. No commitment is made to
  690.   release any future version of this program.
  691.  
  692.     I have only used WreadFiles on three computer systems:
  693.  
  694.  1. Amiga A1000 with 512 kilobytes of chip and 2 megabytes of fast ram
  695.                 using Kickstart 1.2 with Workbench 1.3.  The program did
  696.                 run after invoking NoFastMem, just after reboot, but I
  697.                 cannot guarantee operation with a 512K Amiga. 
  698.  
  699.  2. Amiga A3000/25 system with 10 megabytes total ram using OS 2.04/2.1
  700.     (to version 4.6 only)
  701.  
  702.   3. A4000/040 system with 16 megabytes total ram, OS 3.0. (Version 4.7)
  703.  
  704.     The only background programs I have had running are ConMan on the A1000
  705.   and GRABBIT on the A3000 and A4000. 
  706.  
  707.     I have had one isolated report of a person having a problem with version
  708.   4.2 of this program when he attempted to install it on his GVP hard drive.
  709.  
  710.     Versions 4.2 and 4.3 can not tolerate short sentences which begin with
  711.   leading 0, four digit numerics.  That problem is fixed as of version 4.4.
  712.  
  713.     This software has not been tested in other systems or with all
  714.   possible settings and combinations as commercial software is normally
  715.   tested during the beta test stage.  The user must assume FULL
  716.   responsibility for backing up important files etc. should this program
  717.   malfunction in his or her system or expose a weakness in other software
  718.   while multitasking.
  719.  
  720.     You may find the steady drone of the Amiga voice produced by WreadFiles
  721.   sleep inducing. :}
  722.  
  723.     I hope you find WreadFiles useful and that none of the dire possibilities
  724.    mentioned above ever occurs. 
  725.  
  726.                          M.L. Barlow   25 November 1994
  727.  
  728.  
  729.  ADDR: GEnie: M.BARLOW1
  730.  ----------------------------------------------------------------------
  731.                             VERSION HISTORY
  732.  ----------------------------------------------------------------------
  733.  
  734.   Version 1:  True Basic code.
  735.               The program was inspired by an article by Earl McGhee in
  736.               the March 1987 issue of Jump Disk.
  737.  
  738.   Version 2:  True Basic main program, speech correction coded in C.
  739.               Developed optimized high speed assembly language routines
  740.               for the critical text search and replace functions.
  741.  
  742.   Version 3:  Whole program coded in C. Added icon create/modify feature.
  743.  
  744.   Version 4:  Speech correction sequence reorganized, added "Gang Buster"
  745.               routines for words with common beginnings.  Added number
  746.               conversion. 
  747.  
  748.   Version 4.1 Added modifications to optimize program for OS 2.04 on
  749.               A3000. 
  750.  
  751.   Version 4.2 Added feature to split words to be spoken which have embedded
  752.               capital letters (TrueVision => True Vision).  Reduced
  753.               maximum spoken sentence length from 100 to 23 lines.  Added
  754.               compatibility with ^M, ^M^J and ^J^M EOLs. 
  755.               Discovered and fixed an obscure bug with the sentence processor
  756.               - thanks to Dick Raymond who posted a message to GEnie with 54
  757.               empty lines in it.  First public release.
  758.  
  759.   Version 4.3 Added ASL file selector.  Re-arranged start-up code.  The
  760.               program now holds the translator library open continuously.
  761.               Added gangbuster for words beginning with "mono." Added file
  762.               extension recognition.  Added AGA vocabulary.
  763.  
  764.   Version 4.4 Added gangbuster for words beginning with tri. Modified
  765.               version string for compatibility with 2.1. Added expansion
  766.               of <g,d,r> etc.  Discovered and fixed bug causing guru in
  767.               numeric handler.
  768.  
  769.   Version 4.5 Converted from Manx C to SAS C compiler.  Fixed a Mungwall
  770.               hit.
  771.  
  772.   Version 4.6 Added program icon (WreadFiles.info) tool type recognition
  773.               for reading rate, color scheme, and ASL requester mode. 
  774.               Added OS-2 3-D new look.  Developed 2 user selectable color
  775.               schemes.  Added high contrast color palette at the request of
  776.               Mr. Joe A Chinskey jr. 
  777.  
  778.   Version 4.6M
  779.               Reconstructed version 4.6 after A3000 failure, re-adadapted
  780.               for Manx C on A1000 (Insufficient memory for SAS).  Added
  781.               recognition of some letters formed with combinations of
  782.               slashes and backslashes [like \/\/readfiles]
  783.  
  784.   Version 4.7 Converted back to SAS C 6.51 compiler on A4000.  Added color
  785.               scheme selection to menu.  Replaced a number of custom
  786.               string test routines and macros with standard ANSI equivalents.
  787.               Added LOW-RES screen for full width ASL requester.  Added
  788.               OS-3 menu color pen support with fallback to the previous mode
  789.               for earlier systems.  Fixed a problem switching from command
  790.               colors to reading colors when reading quoted text.
  791.   ----------------------------------------------------------------------
  792.  Version 4.7
  793.   ----------------------------------------------------------------------
  794.       Wread.doc                  36372 ----rwed 25-Nov-94 12:41:xx
  795.       Wread.doc.info               389 ----rw-d 25-Nov-94 09:08:18
  796.       WreadFiles                245368 ----rwed 24-Nov-94 08:29:52
  797.       WreadFiles.info             1339 ----rw-d 25-Nov-94 11:54:41
  798.       WreadFiles.hc.info          1337 ----rw-d 25-Nov-94 10:13:49
  799.   ----------------------------------------------------------------------
  800.